﻿@page "/components/numericfield"

<DocsPage>
    <DocsPageHeader Title="Numeric Field" Component="@nameof(MudNumericField<T>)" />
    <DocsPageContent>

        <DocsPageSection>
            <SectionHeader Title="Basic Usage">
                <Description>
                    Numeric fields are specialized input controls designed for collecting numeric values of any type. Built on the foundation of <MudLink Href="/components/field">fields</MudLink>, they automatically restrict input to valid numbers and provide intuitive controls for incrementing and decrementing values.
                    Use <CodeInline>Min</CodeInline> and <CodeInline>Max</CodeInline> to set boundaries, and <CodeInline>Step</CodeInline> to control increment amounts.
                </Description>
            </SectionHeader>
            <SectionContent Code="@nameof(NumericFieldBasicExample)">
                <NumericFieldBasicExample/>
            </SectionContent>
            <MudAlert Severity="Severity.Warning" Dense="true" Class="mt-3">
                <strong>Default Input Behavior:</strong> Numeric fields use a language-neutral format by default:
                <ul style="list-style:inside; margin-top: 8px;">
                    <li><strong>Decimal Separator:</strong> Always uses a dot (.) regardless of culture</li>
                    <li><strong>Thousands Separator:</strong> Not supported by default</li>
                    <li><strong>Input Format:</strong> [-]digits[.digits] format</li>
                </ul>
                Use <CodeInline>Culture</CodeInline> and <CodeInline>Format</CodeInline> properties for localized input.
            </MudAlert>
            <MudAlert Severity="Severity.Info" Dense="true" Class="mt-3">
                For advanced features like adornments, validation, and form integration, see the <MudLink Href="/components/textfield">TextField documentation</MudLink> which shares the same underlying capabilities.
            </MudAlert>
        </DocsPageSection>

        <DocsPageSection>
            <SectionHeader Title="Common Properties">
                <Description>
                    Control the most frequently used properties to customize the behavior and appearance of numeric fields.
                </Description>
            </SectionHeader>
            <SectionSubGroups>

                <DocsPageSection>
                    <SectionHeader Title="Spin Buttons">
                        <Description>
                            By default, numeric fields display up/down spin buttons for easy value adjustment. Set <CodeInline>HideSpinButtons="true"</CodeInline> to hide these controls while preserving keyboard navigation (arrow keys) and manual input.
                        </Description>
                    </SectionHeader>
                    <SectionContent Class="demo-numericfield" Code="@nameof(NumericFieldHideButtonsExample)" ShowCode="false">
                        <NumericFieldHideButtonsExample/>
                    </SectionContent>
                </DocsPageSection>

            </SectionSubGroups>
        </DocsPageSection>

        <DocsPageSection>
            <SectionHeader Title="Data Binding">
                <Description>
                    Numeric fields support different data binding patterns depending on your requirements for default values and empty states.
                </Description>
            </SectionHeader>
            <SectionSubGroups>

                <DocsPageSection>
                    <SectionHeader Title="Value Types vs Nullables">
                        <Description>
                            Value types always have a default value (e.g., <CodeInline>0</CodeInline> for <CodeInline>int</CodeInline>), so fields won't appear empty initially.
                            Use nullable types (e.g., <CodeInline>int?</CodeInline>) when you want fields to start empty until the user enters a value.
                            <MudAlert Severity="Severity.Info" Dense="true" Class="mt-3">
                                <strong>Tip:</strong> Do not assign null values to <CodeInline>Min</CodeInline>, <CodeInline>Max</CodeInline> and <CodeInline>Step</CodeInline> properties.
                            </MudAlert>
                        </Description>
                    </SectionHeader>
                    <SectionContent Code="@nameof(NumericFieldBindingValueTypesExample)" ShowCode="false">
                        <NumericFieldBindingValueTypesExample/>
                    </SectionContent>
                </DocsPageSection>

                <DocsPageSection>
                    <SectionHeader Title="Update Timing">
                        <Description>
                            By default, numeric fields update the bound value on Enter or when focus is lost. Set <CodeInline>Immediate="true"</CodeInline> to update values as the user types.
                            You can also use <CodeInline>DebounceInterval</CodeInline> to delay updates until the user stops typing, preventing excessive updates during input. The debounced example updates 500ms after typing stops.
                            <MudAlert Severity="Severity.Warning" Dense="true" Class="mt-3">
                                <strong>Note:</strong> Arrow keys and Shift + mouse wheel interactions are not debounced for immediate responsiveness.
                            </MudAlert>
                        </Description>
                    </SectionHeader>
                    <SectionContent Code="@nameof(DebouncedNumericFieldExample)" ShowCode="false">
                        <DebouncedNumericFieldExample/>
                    </SectionContent>
                </DocsPageSection>

            </SectionSubGroups>
        </DocsPageSection>

        <DocsPageSection>
            <SectionHeader Title="Localization & Formatting">
                <Description>
                    Customize how numeric values are displayed and parsed to match different cultural conventions and formatting requirements.
                </Description>
            </SectionHeader>
            <SectionContent Code="@nameof(NumericFieldCultureExample)">
                <NumericFieldCultureExample/>
            </SectionContent>
            <MudAlert Severity="Severity.Info" Dense="true" Class="mt-3">
                <strong>For Floating Point Values:</strong> When using string literals for <CodeInline>Min</CodeInline>, <CodeInline>Max</CodeInline> or <CodeInline>Step</CodeInline>, 
                add a decimal point (e.g., <CodeInline>0.0</CodeInline>) or suffix (e.g., <CodeInline>0.5M</CodeInline> for decimal) to avoid compilation errors.
            </MudAlert>
        </DocsPageSection>

        <DocsPageSection>
            <SectionHeader Title="Mouse Wheel Support">
                <Description>
                    Enhance user experience by allowing value changes via mouse wheel. Hold Shift while scrolling to increment or decrement values by the configured step amount.
                    Use <CodeInline>InvertMouseWheel="true"</CodeInline> to reverse the scroll direction if desired.
                </Description>
            </SectionHeader>
            <SectionContent Code="@nameof(ChangeTheValueWithTheMouseWheelExample)" ShowCode="false">
                <ChangeTheValueWithTheMouseWheelExample/>
            </SectionContent>
        </DocsPageSection>

    </DocsPageContent>
</DocsPage>
